docs: fix documentation gaps identified by full repo audit#662
Closed
cursor[bot] wants to merge 3 commits intomainfrom
Closed
docs: fix documentation gaps identified by full repo audit#662cursor[bot] wants to merge 3 commits intomainfrom
cursor[bot] wants to merge 3 commits intomainfrom
Conversation
Co-authored-by: Miguel Betegón <miguelbetegongarcia@gmail.com>
- Add release and sourcemap to ROUTE_TO_REFERENCE in skill generator with proper titles and descriptions (script/generate-skill.ts) - Add SENTRY_RELEASE, SENTRY_MAX_PAGINATION_PAGES, and SENTRY_CLI_NO_AUTO_REPAIR to configuration.md - Fix OAuth scopes: add missing team:write to DEVELOPMENT.md and self-hosted.md - Add sentry release, repo, team, trial to README command table - Document installer --no-modify-path and --no-completions flags in getting-started.mdx - Fix bun install -> bun add in cli.md detection table - Add yarn to cli.md detection table Co-authored-by: Miguel Betegón <miguelbetegongarcia@gmail.com>
Contributor
Semver Impact of This PR🟢 Patch (bug fixes) 📋 Changelog PreviewThis is how your changes will appear in the changelog. New Features ✨
Bug Fixes 🐛Init
Other
Documentation 📚
Internal Changes 🔧
🤖 This preview updates automatically when you update the PR. |
Contributor
|
Contributor
Codecov Results 📊✅ 134 passed | Total: 134 | Pass Rate: 100% | Execution Time: 0ms 📊 Comparison with Base Branch
✨ No test changes detected All tests are passing successfully. ✅ Patch coverage is 100.00%. Project has 1423 uncovered lines. Coverage diff@@ Coverage Diff @@
## main #PR +/-##
==========================================
+ Coverage 95.54% 95.55% +0.01%
==========================================
Files 220 220 —
Lines 31944 31944 —
Branches 0 0 —
==========================================
+ Hits 30517 30521 +4
- Misses 1427 1423 -4
- Partials 0 0 —Generated by Codecov Action |
BYK
added a commit
that referenced
this pull request
Apr 6, 2026
Replace the three manually-maintained maps (ROUTE_TO_REFERENCE, REFERENCE_TITLES, REFERENCE_DESCRIPTIONS) with 1:1 route-to-file mapping that derives titles and descriptions from route metadata. This matches the strategy used by generate-command-docs.ts and makes it impossible for new routes to produce degraded skill documentation. Closes #662
Member
|
Superseded by #670, which addresses the root cause by eliminating the manual maps in |
BYK
added a commit
that referenced
this pull request
Apr 6, 2026
#670) ## Summary - Replaces the three manually-maintained maps (`ROUTE_TO_REFERENCE`, `REFERENCE_TITLES`, `REFERENCE_DESCRIPTIONS`) in `generate-skill.ts` with 1:1 route-to-file mapping - Titles and descriptions are now derived from route metadata (`brief`), matching the strategy used by `generate-command-docs.ts` - Adding a new route to `app.ts` now automatically produces a correctly-titled reference file with zero manual steps ## Motivation PR #662 identified that `release` and `sourcemap` routes had degraded skill documentation despite the fully automated generation pipeline. The root cause was that `generate-skill.ts` required manual map updates that `generate-command-docs.ts` did not — and the silent fallback (`?? route.name`) masked the problem by producing subtly wrong output that CI's staleness check couldn't distinguish from correct output. Rather than adding validation on top of the manual maps, this PR eliminates them entirely so the two generation pipelines share the same self-healing strategy: one file per visible route, metadata derived from the route tree. ## Trade-off Reference files go from 14 (grouped) to 18 (1:1). The 3 former groupings were: `trace`+`span` → `traces.md`, `team`+`repo` → `teams.md`, `cli`+`init`+`schema` → `setup.md`. Each route now gets its own file. Closes #662
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Full documentation audit of the Sentry CLI repository, cross-referencing the implementation (
src/) against all documentation surfaces (README.md,DEVELOPMENT.md,docs/src/content/docs/,plugins/,script/generate-skill.ts).Gap Report
The detailed gap report is included in
docs/DOCS-GAP-REPORT.mdand covers 10 categories:release,repo,teammissing from READMEreleaseandsourcemapnot inROUTE_TO_REFERENCESENTRY_RELEASE,SENTRY_MAX_PAGINATION_PAGES,SENTRY_CLI_NO_AUTO_REPAIRteam:writescope missing from docsChanges (Top 5 Fixes)
script/generate-skill.ts— Addedrelease→releasesandsourcemap→sourcemapstoROUTE_TO_REFERENCEwith titles and descriptions inREFERENCE_TITLESandREFERENCE_DESCRIPTIONSdocs/src/content/docs/configuration.md— Added documentation forSENTRY_RELEASE,SENTRY_MAX_PAGINATION_PAGES, andSENTRY_CLI_NO_AUTO_REPAIRenvironment variablesDEVELOPMENT.mdanddocs/src/content/docs/self-hosted.md— Added missingteam:writeto OAuth scopes list (code requests 9 scopes, docs listed only 8)README.md— Addedsentry release,sentry repo,sentry team,sentry trialto the command table; updatedsentry issuedescription to mention events subcommanddocs/src/content/docs/getting-started.mdx— Documented installer--no-modify-pathand--no-completionsflags for CI/CD environmentsdocs/src/content/docs/commands/cli.md— Fixedbun install -g→bun add -gin detection table; addedyarnas a detected install method